.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 2011 Tom Cocagne <tom.cocagne@gmail.com>
.\"
.\" Proccess this file with 
.\" groff -man -Tascii srp_auth.7
.\"
.TH srp_auth 7 "March 2011" "User Manuals"
.SH NAME 
srp_auth \- Secure Remote Password Authentication
.SH SYNOPSIS
This package provides support for user authentication via the Secure 
Remote Password Protocol
.SH DESCRIPTION
The
.B srp_auth
package provides an authentication daemon, PAM plugin modules, and associated
management utilties for user authentication via the Secure Remote Password
Protocol (SRP). SRP is a cryptographically strong protocol for password-based
authentication over an insecure network connection. 
.PP
.SH AUTHENTICATION DAEMON
The authentication daemon requires a properly initialized database in order to
run. To create the initial database, use the command:
.B srp_admin create_credential_database 
This command will interactively query
for the username and password of the initial administrator of the database. The
resulting file will default to /var/lib/srp_auth/credentials.db but may be overridden
by passing a specifc file name to the srp_admin command.
Once the database has been created, a port must be chosen for the authentication
daemon to run on.
.PP
The daemon itself is provided as a Twisted plugin and is launched via the
.I twistd
command. Running twistd with no options will print a list of generic arguments
that may be used with the SRP authentication service. The specific options
required for the SRP authentication service are:
.TP
.B --port
.I (required)
The port on which the SRP authentication service will be provided.
.TP 
.B --database
.I (required)
The credential database to use.
.PP 
The authentication daemon does not inherently require root permissions. 
If using a privileged port, however, the twistd arguments
.I --uid
and
.I --gid
may be used to shed root permissions after binding to the ports.
.PP
.SH CLIENT CONFIGURATION
Client configuration for srp_auth user authentication is done in two parts.
First, the /etc/srp_auth.conf file created via the 
.B srp_admin init_host
command. Use of this command is generally preferred over by-hand creation
of the configuration file as it will ensure that all of the settings are 
compatible with the specified authentication server and it will securely 
retrieve the server's public key. A full description of the configuration 
file format is available in the 
.B srp_auth.conf(5) 
man page.

The second required configuration step is modifying the client's PAM 
configuration to use the srp_auth PAM plugin module. This module is named 
.B pam_srp
and may be used on client systems to enable SRP password authentication.
In addition to network based authentication, this module is capable of 
optionally and securely caching user credentials for authentication while 
disconnected from the network. The plugin module supports the following
options:
.TP
.B use_first_pass
.I (optional)
If supplied it forces the module to use a previous stacked module's password 
and will never prompt for the user's password. If no previously stacked
password is available or the password is invalid, the user will be denied 
access.
.TP
.B try_first_pass
.I (optional)
If supplied the module will attempt to use the previous stacked module's
password prior to prompting the user for the password.
.TP
.B srp_config=
.I (optional)
If supplied, the text following the equal sign (no spaces allowed) specifies
that the named configuration section of the srp_auth.conf(5) file should
be used instead of the default.
.TP
.B /path/to/srp_auth.conf
.I (optional)
If supplied, the module will use the specified configuration file instead
of the default: /etc/srp_auth.conf
.SH FILES
.I /etc/pam.d/*
.SH EXAMPLE PAM CONFIGURATION
.nf
auth     required      pam_env.so
auth     sufficient    pam_srp.so
auth     required      pam_unix2.so
.fi
.SH EXAMPLE AUTHENTICATION DAEMON INVOCATION
.nf

twistd --syslog --pidfile=/var/run/srp_auth.pid --port 1234 
       --database=/var/lib/srp_auth/credentials.db
.fi
.SH AUTHOR
Tom Cocagne <tom.cocagne@gmail.com>
.SH "SEE ALSO"
.BR srp_admin (1),
.BR srp_auth (7),
.BR srp_auth.conf (5)
